Capture transaction data

If the create transaction was successful (status equals "INITIALIZED"), the API response will contain several parameters, such as the hostedCheckoutUrl and a transaction "id", both generated by AppDirect. The next step is to capture the "hostedCheckoutUrl" value from the API response, persist some response values in the database, and add the "token" and transaction "id" to the user session. If the transaction failed, the developer should display any appropriate error messaging back to the customer.

Update user session in browser

We recommend saving at least the "token" and transaction "id" in the user session for later validation. Validation will need to occur once the user returns back from the hosted checkout flow to the developer's website.

Persist parameters

It is up to the developer whether or not to save all response values from the transaction in a data store. We recommend saving at least the following values in the database: the transaction "id" in order to be able to call the hosted checkout API again for this transaction (or the "href" url value for "rel" = "self" under "links" object, e.g. the current transaction resource reference for which you can trigger a http GET whenever you want to retrieve the transaction information again), and the "company.id" and the "user.id" (useful for when the customer returns on your site and wants to update his current subscription, update his existing billing details or make a new purchase, because you'll want to include these IDs as part of the hosted checkout API endpoint URL you are posting to and omit the user and company objects from the request body). See the available endpoints definitions and request fields definitions for more information.

Redirect to hostedCheckoutUrl

Now the developer can trigger an HTTP redirect to the received "hostedCheckoutUrl" URL, which will redirect the customer to the AppDirect Hosted Checkout (described in the next section).

Response attributes

Name	Format	Additional Information
token	String	Value generated by developer and sent over in API request
id	String	Transaction identifier generated by AppDirect
expiresOn	Numeric	Timestamp
hostedCheckoutUrl	String	URL to redirect user of current transaction to the AppDirect hosted checkout flow
returnUrl	String	Developer's website URL to return user to at the end of hosted checkout flow
type	String	"PURCHASE" or "BILLING_INFO"
status	String	Enum that can have the following values: INITIALIZED (when transaction successfully initialized, before it gets consumed by user entering the checkout flow and also before expiration) CONSUMED (token was used and user got redirected to purchase flow) EXPIRED (after token expiration) FAILED (means user went through the hosted checkout flow, but either during purchase completion or during application provisioning there was an issue with the application subscription) SUCCESSFUL (after customer is charged)
consumed	boolean	Tells whether transaction was already consumed (true) or not (false). By consumed, we mean the user was redirected to the marketplace once using the 'hostedCheckoutUrl', which 'consumed' the transaction. Whether the user has made an action from there or simply cancelled the transaction or closed his browser is not important. As soon as the user lands on the marketplace, the transaction is marked as consumed and the unique 'hostedCheckoutUrl' of this current transaction can no longer be used. Possible values: true or false
company.id	String	UUID-based.
user.id	String	UUID-based.
links	Array	Array that contains links to resources. Each link element of the array contains 2 fields ["href" and "rel"]. "rel" identify the nature of the link, while "href" is the url to read the actual resource through a simple GET request. Possible values for "rel" as part of the create transaction RESPONSE are: "self": link to the hosted checkout TRANSACTION just created "user": link to the hosted checkout user "company": link to the hosted checkout user's company "product": link to the product associated by this transaction (optional, only applies when 'type' = "PURCHASE") "subscription": link to the subscription associated by this transaction (optional, only applies when 'type' = "PURCHASE" and when an actual purchase was triggered by the customer through hosted checkout online flow)

Example: Successful create transaction API response

{
    "token": "564sdf78-sd98-l123-ssd7-132lkjh534kh",
    "id":   "9834h2w3-j345-34l2-lk32-98hkj234gi34",
    "expiresOn": 1429819131206,
    "hostedCheckoutUrl": "http://localhost:8080/hostedcheckout/9834h2w3-j345-34l2-lk32-98hkj234gi34&token=564sdf78-sd98-l123-ssd7-132lkjh534kh",
    "returnUrl": "https://developer.com/return",
    "type": "PURCHASE",
    "status": "INITIALIZED",
    "consumed": false,
    "company": {
        "id": "295871c8-23df-417f-a783-3a0c090dfe71"
    },
    "user": {
        "id": "d242bf05-13a7-4f7a-a797-e8e83bc4e45c"
    },
    "links": [
        {
            "href": "http://localhost:8080/api/hostedCheckout/v1/transactions/9834h2w3-j345-34l2-lk32-98hkj234gi34",
            "rel": "self"
        },
        {
            "href": "http://localhost:8080/api/account/v2/users/d242bf05-13a7-4f7a-a797-e8e83bc4e45c",
            "rel": "user"
        },
        {
            "href": "http://localhost:8080/api/account/v2/companies/295871c8-23df-417f-a783-3a0c090dfe71",
            "rel": "company"
        },
        {
            "href": "http://localhost:8080/api/marketplace/v1/products/27",
            "rel": "product"
        }
    ]
}

Error response attributes

When the create transaction fails validation (400 Bad Request / 404 Not Found), the response output is an array of json errors. Each json error has the following output parameters:

Name	Format	Additional Information
code	String	Possible error codes can be separated into 2 categories: Data format validation: In this case, the 'code' will hold the property name that has caused the error, unless the validation rule that is failing concerns more than one field at the same time (e.g., if it checks that when field A has X value, then field B must be empty), in such case the 'code' will be empty, and the 'message' will contain details about what is wrong and will most likely list the fields involved. Business-related validation: In this case, the 'code' will hold a self-explaining code from the following list.CodeError descriptionNO_ENTITYReferenced entity could not be found.BAD_UUIDField is not in a valid UUID format.EMAIL_ALREADY_IN_USEProvided email address already exists.VALIDATION_ERRORGeneral validation error. Message will contain more info.SERVER_ERRORReturned if an outstanding error happened during request processing on the server.
message	String	The validation error message

Example: Create transaction API error response payload

# "Data format validation" example:
[
    { 
        "code":"user.email",
        "message":"not a well-formed email address"
    },
    { 
        "code":"company.name",
        "message":"may not be null"
    },
    { 
        "code":"company.name",
        "message":"may not be empty"
    }
]
 
 
# "Business-related validation" example:
[
    { 
        "code":"EMAIL_ALREADY_IN_USE",
        "message":"Email 'bob.gratton.10@appdirect.com' already exist."
    }
]